 (September 1999)(Disk 2).iso/Technical Publications/quicktime/qtdevdocs/images/qtsmban.gif){kind=small}
 (September 1999)(Disk 2).iso/Technical Publications/quicktime/qtdevdocs/images/qt4api.gif)
Inside Macintosh: Macintosh Toolbox Essentials
Previous | Chapter Top | Chapter Contents | Next |
Store your definition function as a resource of type 'WDEF' with an ID from 128 through 4096 . (Window definition function resource IDs 0 and 1 are the standard window definition functions; resource ID 124 is the standard floating window definition function; resource IDs 2 through 123 and 125 through 127 are reserved by Apple Computer, Inc.
Your window definition function can support up to 16 variation codes, which are identified by integers 0 through 15. To invoke your own window type, you specify the window's definition ID , which contains the resource ID of the window's definition function in the upper 12 bits and the variation code in the lower 4 bits. Thus, for a given resource ID and variation code, the window definition ID is
(16 * resource ID) + (variation code)
When you create a window, the Window Manager calls the Resource Manager to access the window definition function. The Resource Manager reads the window definition function into memory and returns a handle to it. The Window Manager stores this handle in the windowDefProc field of the window record. (If 24-bit addressing is in effect, the Window Manager stores the variation code in the lower 4 bits of the windowDefProc field; if 32-bit addressing is in effect, the Window Manager stores the variation code elsewhere.) Later, when it needs to perform a type-dependent action on the window, the Window Manager calls the window definition function and passes it the variation code as a parameter.
The Window Manager defines the window definition function and related constants as described in "Window Definition Function Type and Macros" and "Window Definition Function Enumerators" . For information about creating your own window definition function, see the description of the MyWindow function (MyWindow) .
The window definition function is responsible for drawing the window frame, reporting the region where mouse-down events occur, calculating the window's structure region and content region, drawing the size box, resizing the window frame when the user drags the size box, and performing any customized initialization or disposal tasks.
You can give your window definition function any name you wish. As described in "Window Definition Function Type and Macros" , it takes four parameters and returns a result code:
pascal long MyWindow (short varCode,
WindowPtr theWindow,
short message,
long param);
Your window definition function should perform whatever task is specified by the message parameter and return a function result if appropriate. If the task performed requires no result code, return 0.
The function's entry point must be at the beginning of the function.
You can set up the various tasks as subroutines inside the window definition function, but you're not required to do so.
When you receive a wDraw message, draw the window frame in the current graphics port, which is the Window Manager port.
You must make certain checks to determine exactly how to draw the frame. If the value of the visible field in the window record is false , you should do nothing; otherwise, you should examine the param parameter and the status flags in the window record:
When the Window Manager calls a window definition function with a message of wDraw , it stores a value of type short in the param parameter without clearing the high-order word. When processing the wDraw message, use only the low-order word of the param parameter.
The window frame typically but not necessarily includes the window's title, which should be displayed in the system font and system font size. The Window Manager port is already set to use the system font and system font size.
When designing a title bar that includes the window title, allow at least 16 pixels vertically to support localization for script systems in which the system font can be no smaller than 12 points.
Nothing drawn outside the window's structure region is visible.
When you receive a wHit message, you must determine where the cursor was when the mouse button was pressed. The wHit message is accompanied by the mouse location, in global coordinates, in the param parameter. The vertical coordinate is in the high-order word of the parameter, and the horizontal coordinate is in the low-order word. You return one of the hit return codes defined in "Window Definition Function Enumerators" .
The return value wNoHit might mean (but not necessarily) that the point isn't in the window. The standard window definition functions, for example, return wNoHit if the point is in the window frame but not in the title bar.
Return the constants wInGrow , wInGoAway , wInZoomIn , and wInZoomOut only if the window is active--by convention, the size box, close box, and zoom box aren't drawn if the window is inactive. In an inactive document window, for example, a mouse-down event in the part of the title bar that would contain the close box if the window were active is reported as wInDrag .
When you receive the wCalcRgns message, you calculate the window's structure and content regions based on the current graphics port's port rectangle. These regions, whose handles are in the strucRgn and contRgn fields of the window record, are in global coordinates. The Window Manager requests this operation only if the window is visible.
When you calculate regions for your own type of window, do not alter the clip region or the visible region of the window's graphics port. The Window Manager and QuickDraw take care of this for you. Altering the clip region or visible region may damage other windows.
When you receive the wNew message, you can perform any type-specific initialization that may be required. If the content region has an unusual shape, for example, you might allocate memory for the region and store the region handle in the dataHandle field of the window record. The initialization function for a standard document window creates the wStateData record for storing zooming data.
When you receive the wDispose message, you can perform any additional tasks necessary for disposing of a window. You might, for example, release memory that was allocated by the initialization function. The dispose function for a standard document window disposes of the wStateData record.
When you receive the wGrow message, draw a grow image of the window. With the wGrow message you receive a pointer to a rectangle, in global coordinates, whose upper-left corner is aligned with the port rectangle of the window's graphics port. Your grow image should fit inside the rectangle. As the user drags the mouse, the Window Manager sends repeated wGrow messages, so that you can change your grow image to match the changing mouse location.
Draw the grow image in the current graphics port, which is the Window Manager port, in the current pen pattern and pen mode. These are set up (as gray and notPatXor ) to conform to the Macintosh user interface guidelines.
The grow function for a standard document window draws a dotted (gray) outline of the window and also the lines delimiting the title bar, size box, and scroll bar areas.
When you receive the wDrawGIcon message, you draw the size box in the content region if the window is active--if the window is inactive, draw whatever is appropriate to show that the window cannot currently be sized.
If the size box is located in the window frame instead of the content region, do nothing in response to the wDrawGIcon message, instead drawing the size box in response to the wDraw message.
The function that draws a size box for an active document window draws the size box in the lower-right corner of the port rectangle of the window's graphics port. It also draws lines delimiting the size box and scroll bar areas. For an inactive document window, it erases the size box and draws the delimiting lines.